<?php
//$HeadURL: http://instaforms.googlecode.com/svn/trunk/lib/arbrebinaire/instaformscontroller.interface.php $
//$Revision: 20 $
//$Date: 2012-08-27 18:55:18 +0000 (Mon, 27 Aug 2012) $
//$Author: dev@arbrebinaire.com $
/**
 *
 * Any implementation of the InstaForms controller needs to implement this interface for proper operation
 *
 * PHP version 5
 *
 * @package    com.arbrebinaire.instaforms
 * @author     Francois Hetu <dev@arbrebinaire.com>
 * @copyright  2012 Francois Hetu
 * @version    SVN: $Id: instaformscontroller.interface.php 20 2012-08-27 18:55:18Z dev@arbrebinaire.com $
 */


interface InstaFormsController {
    /*******************************
      REQUEST AND RESPONSE METHODS 
     *******************************/
    
    /**
     * Raw PHP post request accessor
     * 
     * @param $data Any data necessary (context, etc.) needed to get the raw PHP request
     * @return array The raw PHP post request array
     */
    public function getPostRequest($data);
    /**
     * Is the request a post request, and is it AJAX?
     * 
     * @param mixed $data Any data necessary to check both conditions
     * @return boolean Is the request a post request, and is it AJAX?
     */
    public function isAJAXPostRequest($data);
    /**
     * Sends a blank answer to the requester
     * 
     * @param $data Any data (context, etc.) needed to send an empty response
     */
    public function sendEmptyResponse($data);
    
    
    /*******************************
          PERSISTANCE METHODS 
     *******************************/
    
    /**
     * Given an InstaformsFormDataObject, persist it
     * 
     * @param InstaformsFormDataObject $formObject
     * @return boolean True if successful
     */
    public function saveFormData(InstaformsFormDataObject $formObject);
    
    public function getFormData($formId);
    
    
    /**
     * Saves an answer associated with the form of id $formId
     * 
     * @param mixed $formId
     * @param array $answer
     * 
     * Format of $answer:
     * 
     * array(
     * )
     * 
     * @return boolean True if successful
     */
    public function saveAnswer($formId, array $answer);
    
    
    /**
     * Answers accessor
     * 
     * @param $formId The form unique ID
     * @return array The answers
     * 
     * Format of return value:
     * array(
     *      //Answer 1
     * 		array(
     * 				'timestamp' => 1345142485, //Unix timestamp
     *  			'values'    => array(
     *  									array(
     * 				     							'question_id' => 'the_unique_id_1',
     *                   							'sentence'    => 'The question 1 at that particular time',
     *   			     							'answer_part' => 'The answer to this question'
     *                  					),
     *                  					array(
     *                  							'question_id' => 'the_unique_id_2',
     *                  							'sentence'    => 'The question 2 at that particular time',
     *                                              'answer_part' => 'The answer to this question'
     *                  					)
     *  			   				)
     * 		)
     * 		//Answer 2: a question (3) was added to the form after answer 1 was given, hence the 3rd answer_part
     * 		array(
     * 				'timestamp' => 1345142521, //Unix timestamp
     *  			'values'    => array(
     *  									array(
     * 				     							'question_id' => 'the_unique_id_1',
     *                   							'sentence'    => 'The question 1 at that particular time',
     *   			     							'answer_part' => 'The answer to this question'
     *                  					),
     *                  					array(
     *                  							'question_id' => 'the_unique_id_2',
     *                  							'sentence'    => 'The question 2 at that particular time',
     *                                              'answer_part' => 'The answer to this question'
     *                  					),
     *                  					array(
     *                                             'question_id' => 'the_unique_id_3',
     *                                             'sentence'    => 'The question 3 at that particular time',
     *                                             'answer_part' => 'The answer to this question'
     *                  					)
     *  			   				)
     * 		)
     * )
     * 
     */
    public function getAnswers($formId);
    
    /*******************************
               ACL METHODS 
     *******************************/
       
    /**
     * Checks if the user has access to the form
     * 
     * @param mixed $data Any data to use to check if this user has access to this form
     * @return boolean True if user has access
     */
    public function userHasAccessToForm($formId, $data);
    
    /**
     * Checks if the user can modify the form
     * 
     * @param mixed $data Any data to use to check if this user has access to this form
     * @return boolean True if user can modify the form
     */
    public function userCanModifyForms($data);
    
    
    /*******************************
               I18N METHOD 
     *******************************/
    
    /**
     * Translation function
     * 
     * @param string $str The string to be translated
     * @param string $lang The language 
     * @param mixed $dic A dictionary 
     */
    public function __($str, $lang, $dic);
    
    
    /*************************************
      FORM CREATION AND RENDERING METHODS 
     *************************************/
    
    /**
     * Checks if the form is accepting answers at the present time
     * against values entered by the form creator
     * 
     * @param mixed $formId The form unique Id
     * @return boolean Is the form accepting answers at this time?
     */
    public function formAcceptsAnswers($formId);
    /**
     * 
     * @param mixed $formId
     */
    public function createForm($formId, $formAction);
    public function renderForm($formId);
    
}